Reconocimiento: Gran parte de los documentos introductorios son una traducción libre desde al material preparado y compartido por el grupo SASAP del NCEAS en su sitio SASAP-Training de en GitHub.
La reproducibilidad es fundamental en la ciencia, ya que la ciencia está basada en observaciones empíricas acopladas a modelos explicativos. Si bien la reproducibilidad incluye el ciclo de vida completo de la ciencia y además incluye aspectos como la consistencia metodológica y tratamiento del sesgo, en este curso nos enfocaremos a la reproducibilidad computacional, esto es la habilidad para documentar datos, análisis y modelos en forma suficiente para que otros investigadores sean capaces de entender, reproducir y re-ejecutar los pasos computacionales que nos permitieron llegar a los resultados y sus conclusiones.
@ioannidis_why_2005 destacó la crisis en reproducilidad de la ciencia cuando escribió que “La mayoría de los descubrimientos son falsos para la mayoría de los diseños de investigación, en la mayoría de las áreas de investigación” (“Most Research Findings Are False for Most Research Designs and for Most Fields”). Ioannidis indica la formas en que el proceso de investigación ha inflado los efectos de los tamaños muestrales y los tests de hipótesis que codifican los sesgos existentes. Investigaciones posteriores han confirmado que la reproducibilidad es baja para muchos campos de la ciencia, incluyendo genética \[@ioannidis\_repeatability\_2009\], ecología \[@fraser\_questionable\_2018\], y psicología \[@open\_science\_collaboration\_estimating\_2015\], entre muchas otras. Por ejemplo, el efecto del tamaño de muestra en la psicología se ha mostrado que decrece significativamente cuando se repiten los experimentos (fig. @ref(fig:effectsize)).
Efecto del tamaño de muestra descrese en experimentos repetidos (Open Sieze Collaboration 2015).
Este curso está basado en el desarrollado por el Arctic Data Center en NCEAS y ha sido modificado y traducido por Jorge Cornejo-Donoso.
Antes de comenzar con el material para la investigación reproducible, es necesario que aprendamos sobre algunas herramientas fundamentales, como son RStudio, Git/Github y con posterioridad comenzaremos a trabajar con RMarkDown.
En este capítulo veremos:
Las reproducibilidad es fundamental en la ciencia, que a su vez se
basa en observaciones empíricas con las que se construyen o define
modelos explicativos.
La reproducibilidad por su parte, envuelve todo el ciclo de vida de la
ciencia, incluyendo aspectos como la consistencia metodológica y el
tratamiento del sesgo. En este curso nos vamos a enfocar en la
reproducibilidad computacional, entendiendo esto como
la habilidad de documentar datos, análisis y modelos con la suficiente
información para que otros investigadores sean capaces de entender e
idealmente reproducir, paso a paso, el proceso que no a los resultados y
conclusiones de nuestra investigación.
El primer paso para abordar este problema es ser capaz de evaluar los datos, análisis y modelos con los que se sacan las conclusiones. Considerando cuales son las prácticas más comunes, esto resulta bastante difícil ya que la generalidad de los datos no se encuentran disponibles, la sección sobre la metodología de los informes y papers no describe en detalle las aproximaciones computacionales utilizadas o los análisis y además los modelos son generalmente realizados en programas gráficos o, cuando se usan ambientes tipo script, el código no se hace disponible.
Sin embargo todos estos inconvenientes pueden ser fácilmente solucionados. Los investigadores pueden lograr la reproducibilidad computacional con aproximaciones basada en las aproximaciones de ciencia libre (open science), siguiendo pasos simples para archivar y publicar (libremente) los datos y códigos fuentes utilizados, describiendo el flujo de trabajo y permitiendo de esta forma trazabilidad de los resultados (ej.:, @hampton_tao_2015, @munafo_manifesto_2017).
El flujo del trabajo científico encapsula todos los pasos desde la adquisición de los datos, limpieza, transformación, integración, análisis y visualización.
Captura de un flujo de trabajo científico y procedencia de múltiples pasos necesarios para reproducir un resultado científico desde los datos crudos.
Una representación del flujo de trabajo puede variar desde simples diagramas de flujo (fig. @ref(fig:workflow)) a códigos totalmente ejecutables. Códigos de R y python son una forma literal de plasmár el flujo de trabajo lo que cuando son publicados por investifacores, como versiones específicas del código y los datos asociados, permite la repetibilidad de sus cómputos en forma simple y de esta forma entender la procedencia de las conclusiones.
En este capítulo veremos:
Ahora que ya conoce un poco de la sintaxis básica de R, podemos comenzar a aprender sobre RMarkdown. La experiencia nos dice que te vas a volver loco haciendo los análsis o modelos en los cuales trabajes y vas a fallar en generar un flujo de trabajo reproducible. Peor aún, si tratas de desarrollar código directamente en la consola de R. RMarkdown es realmente clave para la investigación colaborativa, es por esto que vamos a comenzar rapidamente a aprender como usarlo y lo seguiremos uasndo durante el resto del curso.
Un archivo de RMarkdown nos va a ayudar a tejer un texto markdown con fragmentos de código de R que es evaluado y cuyas salidas, como tablas y gráficos, son incluidas en el documento final.
Para abrir un nuevo documento de RMarkdown siga los siguiente pasos:
File -> New File -> RMarkdown… -> Document of output format HTML, OK.
Captura de pantalla de la interfase para la creación de un proyecto nuevo de RStudio.
Le puede dar un título como “Mi Proyecto”. Luego clic en OK.
OK, primero que todo: Al abrir el archivo, vamos a ver un 4° panel de la consola de RStudio, este panel es un editor de texto que nos permite abrir varios archivos en un único panel.
Ahora démosle una mirada a este archivo que acabamos de crear - a primera vista se puede ver que no está en blanco; hay un texto inicial que se entrega por defecto. Hay algunas cosas que podemos identificar en el texto:
Imagen con el código fuente de un archivo RMarkdown.
Lo primero que vamos a hacer es generar el código HTML (Knit
HTML) haciendo clic en la pelota de lana azul en la parte superior del
panel con el archivo RMarkdown. Cuando haga clic por primera vez en este
botón, RStudio pedirá que guarde el archivo. Cree un nuevo directorio en
algún lugar que le sea fácil encontrarlo posteriormente (por ejemplo
Escritorio o Mis Documentos), dele un nombre que tenga sentido y le
permita recordarlo después (ej: clase_rmarkdown).
Imagen con el código fuente y pagina resultante de un archivo RMarkdown.
¿Que cosas puede notar entre al comparar los dos archivos?
Las secciones de código R plomas están rodeadas de 3
tics y {r LABEL}. Estas secciones son evaluadas por R,
generando una salida de texto en el caso de summary(cars) y
de un gráfico en el caso de plot(pressure).
Note como el código plot(pressure) no se muestra en la
salida HTML porque la sección de código R tiene la opción
echo=FALSE.
Algunos otros detalles…
Este archivo de RMarkdown tiene 2 lenguajes incluidos: R y Markdown.
Aun no sabemos mucho de R, pero ya puede ver que estamos tomando el resumen de los datos llamados ‘cars’ y luego los graficamos. Hay mucho más para aprender sobre R y vamos a trabajar eso en las próximas clases.
El segundo lenguaje que incluye el archivo es Markdown. Este es un lenguaje que para dar formato a texto plano y tiene aproximadamente 15 reglas para conocer.
Vea la siguiente sintaxis:
#, ##**palabra**Hay muchas tablas de consejos cheatsheets que te puede utilizar para obtener ayuda, una de esas está incluida en RStudio: para abrirla vaya a Help > Markdown Quick Reference
Importante: El símbolo de gato, número o para los
milenials hashtag # tiene un significado diferente al que
reconoce R cuando es usado en Markdown:
# es equivalente a
######. Es sólo una cuestión de estilos.# es un “título nivel 1”, lo que
significa que es la fuente de mayor tamaño y que está al tope de la
jerarquía. ### es un título nivel 3 y se muestra anidado
bajo el título # y ##.Más sobre esto en: http://rmarkdown.rstudio.com/
OK. Ahora practiquemos con algunos comandos de R.
Cree una nueva sección en en su RMarkdown siguiendo alguno de estos pasos:
Ahora escribamos un poco de código R.
x <- 4*3
x
Note que al apretar la tecla Enter el comando no se ejecuta; recuerde que esto es sólo un archivo de texto. Para ejecutar las secciones de código R (secciones en plomo) se deben enviar a la consola. ¿Cómo se hace eso?
Hay varias formas de hacerlo:
Agregue otros comandos a su archivo. Ejecútelos de las tres formas indicadas más arriba. Finalmente, guarde su archivo RMarkdown.
Hasta ahora hemos aprendido la sintaxis básica y conceptos de programación en R, como navegar en RStudio y RMarkdown, pero no hemos hecho nada complicado o interesante aún. Aquí es donde las funciones de R son útiles.
Una función es una forma de agrupar una serie de comandos para desarrollar una tarea en una forma reusable. Cuando una función es ejecutada, se produce un valor de salida. Nosotros generalmente decimos que “llamamos” una función cuando la ejecutamos. Lo interesante sobre las funciones es que pueden ser creadas por los usuarios y guardadas como un objeto usando el operador de asignación (‘<-’), de esta forma es posible escribir una función para lo que sea que necesitemos. Tenga en cuenta que R tiene una colección gigantesca de funciones pre-existentes, las que además son expandibles con paquetes o librerías. Para comenzar, vamos a usar algunas funciones de R básicas ya incluidas.
Todas las funciones se llaman usando la misma sintaxis: nombre de la
función seguido de un paréntesis donde se entrega lo que necesite la
función para funcionar. Las piezas de información que la función
necesita para hacer su trabajo se conocen como argumentos. De esta
forma, la sintaxis para usar una función se ve así:
valor_resultante <- nombre_de_función(argumento1 = valor1, argumento2 = valor2, ...).
Para tomar un ejemplo muy simple, vamos a utilizar una función que
calcula el promedio, mean(). Como se puede imaginar, esta
función calcula el promedio de los números entregados como
argumentos.
Creemos un vector con pesos:
peso_kg <- c(55, 25, 12)
y ahora usemos la función mean para calcular el peso
promedio.
mean(peso_kg)
## [1] 30.66667
¿Qué pasa ahora si sabe cuál es la función que necesita pero no cómo funciona? Afortunadamente RStudio entrega una forma muy fácil para acceder a las páginas de documentación y ayuda.
Para acceder a la ayuda para la función mean, entre el
siguiente comando en la consola:
?mean
Esto abrirá el panel de ayuda en la sección inferior derecha de RStudio.
Las páginas de ayuda están dividas en secciones, la documentación está en inglés:
Ejercicio: Hable con su(s) compañero(s) y dele una mirada a las ayudas de algunas funciones que usted espera que existan. Aquí les dejo algunas ideas:
?getwd(),?plot(),min(),max(),?log().
También existe ayuda para cuando usted no está seguro del nombre de la función, en esos casos solo es necesaroio usar doble símbolo de pregunta:
??install
No todas las funciones tienen (o requieren) argumentos:
date()
## [1] "Wed Oct 9 17:02:07 2024"
Hasta ahora hemos aprendido como asignar valores a objetos de R y lo
que es una función, pero no hemos hecho nada aún con datos reales. Ahora
vamos a introducir la función read.csv, que nos permite
cargar a R datos reales desde un archivo CSV. Esta función se usa
generalmente en las primeras líneas del código que escribamos.
Ya que esta será nuestra primera vez usando esta función, primero
leeremos la página de ayuda de read.csv. La ayuda tiene
mucha información, mostrando que la función acepta muchos argumentos,
sin embargo el primero de ellos es el más importante - tenemos que
decirle que archivo es el que va a leer.
Navegue al set de datos de Craig Tweedie @tweedie_2009 que está publicado en el Arctic
Data Center y descargue el primer archivo csv llamado
“BGchem2008data.csv”. Mueva este archivo desde su carpeta de Descargas a
un directorio de fácil acceso. Yo recomiendo crear un directorio llamado
datos en el directorio que creó anteriormente para las
otras actividades de esta clase.
Ahora tenemos que indicrle a la función read.csv como
encontrar el archivo que queremos leer. Para esto se usa el argumento
file (archivo) que se puede ver en la sección usage (uso)
de la página de ayuda. En RMarkdown, se pueden usar path absolutos (que
comienzan con su directorio ~/) o path relativos, que son
relativos a la ubicación del archivo RMarkdown. RStudio
y RMarkdown tiene la capacidad de autocompletar cuando se usan paths
relativos, por lo que usaremos ese sistema. Asumiendo que ya movió el
archivo a el directorio dentro de la carpeta
archivos_clase_R llamada datos, su función
read.csv puede ser llamada de la siguiente forma:
bg_chem <- read.csv("datos/5.1_BGchem2008data.csv")
## El nombre fue cambiado para hacer referencia que el archivo csv se usa en el capítulo 5.
Ahora debería tener un objeto en R llamado bg_chem de la
clase data.frame en su ambiente de trabajo. Verifique
data.frame existe y contiene los datos.
Note que en las páginas de ayuda hay una gran cantidad de argumentos
que no fueron necesarios de utilizar. Algunos argumento en las llamadas
a funciones son opcionales y algunos otros son requeridos. Los
argumentos opcionales son mostrados en la sección de uso como un par
nombre = valor, donde se muestra el valor que usa esa
opción por defecto. Si usted no especifica el valor para la oción en
particular, la función asume el valor por defecto (ejemplo:
header = TRUE para read.csv). Los argumentos
requeridos sólo muestran el nombre del argumento, sin un valor asociado.
Fíjese que el único argumento requerido para read.csv es
file.
Siempre se puede especificar un argumento de la forma
nombre = valor. Pero si no lo hace, R intentará
identificarlos basado en el orden en que fueron entregados. De esta
forma, en el comando de más arriba, se asume que queremos
file = "data/5.1_BGchem2008data.csv", ya que file
es el primer argumento. Si queremos agregar algún otro argumento, por
ejemplo stringsAsFactors, vamos a necesitar especificarlos
usando nombre = valor, ya que el segundo argumento es
header. Para las funciones que llamo comúnmente, uso esto
sólo para los primeros 2 argumentos, para los que están en la 3a
posición o más alla siempre uso el par nombre = valor.
Muchos usuarios de R (incluyéndome) sobrescriben el argumento por
defecto de stringsAsFactors usando la siguiente
llamada:
bg_chem <- read.csv("data/5.1_BGchem2008data.csv", stringsAsFactors = FALSE)
Esto muy útil, ya que de otra forma las columnas que contiene datos tipo strings son transformados a factores, pudiendo generar esto problemas y confusiones.
data.framesUn data.frame en R es una estructura de datos de dos
dimensiones, es similar a como se comporta una hoja de cálculos. Un
data.frame es una colección de filas y columnas de datos,
donde cada columna tiene un nombre y representa una variable, siendo
cada fila a una medición de esa variable. De esta forma, cuando
ejecutamos read.csv, el objeto bg_chem fue
creado como un objeto tipo data.frame. Hay muchas formas
para explorar un data.frame en R y RStudio. A continuación
mostramos algunos:
bg_chem en el panel
Environment.bg_chem en el panel de
Environmenthead(bg_chem) en la consola.View(bg_chem) en la consola.Usualmente las funciones se ejecutan en columnas individuales de un
data.frame. Para llamar a una columna específica se usa el
operador $. Por ejemplo, digamos que se quiere mirar las
primeras filas sólo de la columna Date. Para esto se debe
ejecutar en la consola:
head(bg_chem$Date)
## [1] "2008-03-21" "2008-03-21" "2008-03-21" "2008-03-21" "2008-03-21"
## [6] "2008-03-22"
¿Cómo se puede calcular la temperatura promedio de las muestras tomadas por el CTD?
mean(bg_chem$CTD_Temperature)
## [1] -0.9646915
O si quisiéramos guardar este promedio como una variable para ser utilizada después:
temp_promedio <- mean(bg_chem$CTD_Temperature)
También es posible crear algunos gráficos simples utilizando este
operador ($).
plot(bg_chem$CTD_Depth, bg_chem$CTD_Temperature)
En R existen muchas herramientas y funciones más avanzadas para crear mejores gráficos (incluso con una sintaxis más simple). Veremos algunas de ellas en capitulos posteriores.
Ejercicio: Tome algunos minutos en explorar este set de datos. Pruebe algunas funciones en las columnas utilizando el operador
$para seleccionar una columna única. Experimente haciendo gráficos y generando resúmenes de los datos.
Si se obtiene un error cuando se trata de generrl el PDF, donde dice que su computador no tiene la instalación de LaTeX, existen dos posibles problemas:
Si usted ya usa LaTeX (para escribir papers por ejemplo), seguro que su problema esté en la segunda categoría. Arreglar esto sólo requiere redireccionar RStudio a donde este instalado LaTeX, pero esto no lo explicaremos acá.
Si su problema es que no tiene instalado LaTeX y está seguro
que no lo tiene! puede usar el paquete de R
tinytex, este se instala muy fácilmente y es reconocido
automáticamente por RStudio. Para hacer esto sólo necesita tener
derechos de administrador del computador.
Para instalar tinytex ejecute en la consola:
install.packages("tinytex")
tinytex::install_tinytex()
Esto puede ocurrir porque no completó el comando: ¿Se muestra un
pequeño signo + en su consola? R le esta diciendo que está
esperando a que termine de entregar los comandos. En el ejemplo de más
abajo falta cerrar el paréntesis.
> x <- seq(1, 10
+
Se puede simplemente cerrar el paréntesis y apretar enter, o
esc dos veces, lo que va a cancelar cancelar la ejecución
del comando.
Este error es muy común en usuarios nuevos:
Error in mean(myobject) : object 'myobject' not found
Esto significa que el objeto llamado myobject no existe
en el ambiente de trabajo. Las razones más comunes para este error
son:
myobject <- read.csv(...).RMarkdown es una excelente forma de generar análisis literales y flujos de trabajo reproducibles. Aquí hay un ejemplo en inglés de un flujo de trabajo real escrito utilizando RMarkdown.
En este capítulo veremos:
El dilema de usar nombres como descriptor de versiones.
Cada archivo en un proceso científico sufre de cambios. Los manuscritos son editados. Las figuras son revisadas. Los códigos se corrigen cuando se encuentran problemas. Los archivos de datos se combinan, los errores son corregidos, se dividen y combinan nuevamente. En el curso de un análisis simple, uno puede esperar miles de cambios en los archivos. Y aún así, todo lo que usamos para identificas este sinnúmero de cambios son los simples nombres de archivos (fig. @ref(fig:finalDoc2)). Teniendo esto en consideración, es lógico pensar que debe existir una forma mejor… Y si la hay, se conoce como Control de Versiones.
Un sistema de control de versiones ayuda a seguir
lso cambios que se realizan a nuestros archivos, sin el desastre que
resulta de utilizar sólo el nombre de los archivos. En los sistemas de
control de versiones como git, se registra no sólo el
nombre del archivo, si no que además su contenido, de esta forma, cuando
el contenido cambia, se puede identificar que partes estaban y donde. El
registro además contiene la relaciones entre las versiones, de esta
forma se tiene un historial de todos los cambios deribados de las cada
una de las versiones y es fácil dibujar un gráfico que muestre los
cambios que ha sufrido un archivo, con sus versiones previas y aquellas
derivadas (Fig. @ref(fig:figVersiones2))
Evolución de las versiones de un archivo.
Los sistemas de control de versiones asignan un identificador a cada
versión de cada archivo, manteniendo un registro de como están
relacionados entre ellos. Además, estos sistemas permiten generar ramas
laterales a una versión, la que puede ser fusionada de regreso a la
tronco principal. Es posible además tener múltiples copias en
múltiples computadores como respaldos y para trabajar colaborativamente.
Finalmente, se pueden incluir etiquetas (tags) a versiones particulares,
de esta forma es fácil retornar la versión que tenían los archivos
cuando fueron etiquetados. Esto es particulamente útil para identificar
una versión exacta de los datos, código y texto, por ejemplo, de un
manuscrito que fue enviado para ser publicado, este puede ser el caso de
la etiqueda R2 en la figura @ref(fig:figVersiones2).
Es importante hacer la distinción entre git y GitHub.
Diferencia entre git y GitHub.
La captura de pantalla en la figura @ref(fig:webGitHub) muestra una copia de un repositorio almacenado en GitHub, con el listado de archivos y directorios, indicando cuando fueron modificados, incluyendo información acerca de quien hizo los cambios y una pequeña descripción de los cambios realizados.
Captura de pantalla de un repositorio en GitHub.
Si nos metemos en los “commits” del repositorio (fig. @ref(fig:githubCommits)), podemos ver la
historia de los cambios que se le han realizado. Por ejemplo, se ve que
kellijohnson y seananderson hicieron algunos
cambios durante junio y julio:
Captura de pantalla de los Commits de un repositorio en GitHub.
Si entramos ahora a ver los cambios realizados el 13 de julio (fig. @ref(fig:githubDiferencias)), podemos saber exactamente cuales fueron los cambios realizados a cada archivo:
Captura de pantalla donde se presentan las diferencias entre dos versiones alojadas en un repositorio de GitHub.
Monitorear estas modificaciones, como se relacionan a cada una de las versiones de un software en particular y a los archivos es exactamente para lo que fueron diseñados git y GitHub. Vamos a mostrar como estos sistemas pueden ser realmente efectivos para monitorear las versiones de códigos científicos, figuras y manuscritos y de esta forma tener flujos de trabajo reproducibles.
Como usuario de git usted tiene que entender algunos conceptos básicos asociados a los sets de cambios con versiones y como estos son almacenados y se mueven a través del repositorio. Cualquier repositorio de git puede ser clonado, de esta forma existe en forma local y remota. Pero cada uno de estos repositorios clonados son una copia simple de todos los archivos y del historial de los cambios que se han realizado, lo que son almacenados en un forma repositio git particular. Para nuestros propósitos, tenemos que considerar un repositorio de git simplemente como un directorio que contiene adicionalmente un set de metadatos relacionado las versiones.
En un directorio local donde git fue habilitado, el directorio contiene la versión actual de todos los archivos del repositorio. Estos archivos de trabajo están unidos a un directorio escondido que contiene el ‘Repositorio local’, el que a su vez contiene todos los otros cambios que se han realizado a los archivos y los metadatos sobre las versiones.
De esta forma, cuando se está usando git para trabajar con archivos,
se pueden usar los comandos de git para indicar específicamente que
cambios a los archivos de trabajo deben ser definidos para las versiones
(usando el comando git add) y cuando grabar estos cambios
como una versión en el repositorio local (usando el comando
git commit).
Los demás conceptos se relacionan a la sincronización de los cambios
en el repositorio local a un repositorio remoto. El comando
git push se usar para enviar los cambios realizados en
forma local a un repositorio remoto (posiblemente en GitHub) y el
comando git pull es usado para traer los cambios del
repositorio remoto y unirlos al repositorio local.
Diagrama de flujo del ciclo de vida de git.
git clone: Copia todo el repositorio remoto a uno
local.git add (stage): Notifica a git de monitorear un set
particular de cambios.git commit: Almacena los cambios realizados como una
versión.git pull: Combina los cambios de un repositorio remoto
a nuestro repositorio local.git push: Copia los cambios de nuestro repositorio
local al repositorio remoto.git status: Determina el estado de los archivos en el
repositorio local.git log: Imprime el historial de cambios en el
repositorio.Estos siete comandos son la mayoría de los comando que va a necesitar para utilizar git en forma exitosa. Pero todo esto es demasiado abstracto, mejor exploremos estos conceptos utilizando ejemplos reales.
Empecemos creando un repositorio en GitHub, luego editaremos algunos archivos.
sasap-test.Captura de pantalla de la creación de un repositorio nuevo en GitHub.
¡Usted acaba de crear su primer repositorio! Este repositorio fue creado con un par de archivos que GitHub hace por usted, son los archivos README.md, LICENSE y .gitignore.
Captura de pantalla con el repositorio recién creado llamado sasap-test.
Para hacer cambios menores a archivos de texto se puede utilizar la
interfase web de GitHub. Navegue al archivo README.md en el
listado de archivos y habilite la edición haciendo clic en el icono del
lápiz. Este es un archivo normal con el formado Markdown, ahora
se puede editar, agregando o removiendo texto. Cuando haya terminado,
incluya un mensaje de commit y luego haga clic en el botón
Commit changes.
Captura de pantalla con la interfase web de GitHub para la edición de documentos de texto.
Captura de pantalla con la interfase web de GitHub para la confirmar de los cambios realizados al documento de texto (commit changes).
Felicitaciones, ahora usted acaba de confirmar (commit) los cambios, ahora es el autor de la primera versión de este archivo. Si navega de regreso a la página del repositorio GitHub, puede ver la lista de los cambios confirmados (commits) ahí, así como la visualización del documento generado a partir del archivo README.md.
Captura de pantalla con la interfase web los cambios corfimados (commits) y de la visualización de la página README.md.
Expliquemos algunas cosas sobre esta ventana. Representa una vista del repositorio que acaba de crear, hasta ahora mostrando todos sus archivos. Para cada archivo, muestra la fecha de la última modificación y el mensaje asociado al commit que se utilizó para describir los cambios realizados. Esta es la razón por qué es tan importante escribir buenos mensajes, que contengan información relevante cuando se hace el commit. Además, el título azul sobre el listado de archivos muestra el commit más reciente, con su mensaje asociado y su identificados SHA. Ese identificador SHA es la clave para el set de versiones. Si hace clic en el identificador SHA (810f314), va a mostrar los cambios que se hicieron en ese commit en particular.
En la siguiente sección vamos a usar el URL de GitHub del repositorio
que acaba de crear y lo usaremos plara clonarlo (clone) a
un repositorio en nuestra máquina local y así editar los archivos con
RStudio. Para eso, primero tenemos que copiar el URL de GitHub, que
representa la dirección del repositorio:
Captura de pantalla para clonar un repositorio GitHub.
RStudio incluye soporte para Git como sistema de control de versiones, pero esto sólo ocurre si estamos trabajando en un Proyecto de RStudio (RStudio project folder). En esta sección vamos a clonar el repositorio que se creó en GitHub y lo vamos a dejar un repositorio local de un proyecto de RStudio.
Esto es lo que vamos a hacer:
Comience creando un New Project… en RStudio, seleccione la
opción Version Control y pegue el URL de GitHub que copió en el
espacio para repositorio remoto (Repository URL). Si bien usted
puede darle el nombre que quiera al repositorio local, se usa
típicamente el mismo nombre que el que se tiene en GitHub, de esta forma
se mantiene un grado de correspondencia. Usted puede elegir cualquier
directorio para su copia local, en mi caso use el directorio
development (fig. @ref(fig:githubClone)).
Captura de pantalla para la creasción de un proyecto de RStudio clonando un repositorio remoto.
Un vez que haga clic en Create Project (crear proyecto),
una nueva página de RStudio se abrirá con todos los archivos copiados
localmente desde el repositorio remoto. Dependiendo de como esté
configurada la versión de RStudio, la posición y tamaño de los paneles
puede cambiar, pero generalmente todos van a estar presentes, incluyendo
los paneles Git y el listado de archivos (Files) que
fueron creados en el repositorio remoto.
Captura de pantalla de la interfase del projecto de RStudio con el clon local de repositorio.
En la figura @ref(fig:githubCloneLocal)
puede ver que apareció un archivo llamado sasap-test.Rproj
y que están los otros 3 archivos que se crearon con el repositorio
remoto de GitHub (.gitignore, LICENSE y
README.md).
En el panel Git en RStudio se pueden ver 2 archivos. Este es
el panel de estatus donde se se muestran todos los archivos del
repositorio en los cuales se han realizado modificaciones. En este caso,
el archivo .gitignore se muestra con una M que
significa Modificado y sasap-test.Rproj con un
? ? para indicar que este archivo no está siendo monitoreado.
Esto significa que git no tiene registro de ninguna version para este
archivo y que no sabe nada acerca de el. A medida que usted vaya tomando
decisiones sobre el control de versiones en RStudio, estos iconos van a
ir cambiando para reflejar el estatus de la versión actual de cada uno
de los archivos.
A continuación vamos a hacer clic en el botón History (historial, es el reloj que aparece en la primera fila al interior del panel ed Git), esto despliega una ventana con el registro de los cambios que se han realizado y, en este caso, deben ser idénticos a lo que usted vio en GitHub. Al hacer clic en cada fila del historial, podrá ir viendo exactamente que fue agregado y cambiado en cada uno de los commits en este repositorio.
Historial de los cambios realizados en el repositorio local.
Ahora hagamos algunos cambios al archivo README.md en RStudio. Agregue una sección nueva con un block de markdown como este:
## Git desde RStudio
Desde la interfase de RStudio, es posible hacer las mismas acciones con el sistema de versiones que se hicieron en GitHub
y mucho más. Además en RStudio se tienen las ventajas propias de programar en un IDE con completación de comandos y otras
características que hacen nuestro trabajo más fácil.
- Agregar archivos al control de versiones
- Ccommit cambios
- Push commits a GitHub
Una vez que los haya guardado, podrá ver en forma inmediata el archivo README.md en el panel Git (fig. @ref(fig:rstudioPanelStatus)), marcado con una M de modificación. Ahora usted puede seleccionar este archivo en el panel de Git y hacer clic en Diff para ver los cambios (comparando las diferencias) que guardó (note que estos cambios no se han confirmado (commit) aun a su repositorio local).
Panel de estado de los cambios en los archivos.
En la figura @ref(fig:rstudioDiferencias) se muestra como se ven los cambios comparados con el archivo original. La líneas nuevas se destacan en color verde y en rojo las que fueron eliminadas.
Ventana que presenta las diferencias entre la versión almacenada en el repositorio y los últimos cambios realizados.
Para confirmar los cambios que se acaban de hacer en el archivo README.md, selecciones la caja de selección Staged a lado del nombre del archivo, este le dice a Git cuales son los cambios que quiere sean incluidos en el commit, escriba un mensaje describiendo que cambios se hicieron y por qué y finalmente haga clic en boton Commit (fig. @ref(fig:rstudioCommit1)).
Captura de pantalla con un mensaje describiendo la confirmación (commit) que se realizará.
Note que algunos de los cambios en el repositorio,
.gitignore y sasap-test.Rproj, aun no se han
confirmado y no serán parte del commit. En otras palabras, aun
existen cambios pendientes para ser registrados en el repositorio. Usted
vará una notificación que indica (en inglés):
Your branch is ahead of ‘origin/master’ by 1 commit.
Lo que se traduce a: _Su rama esta más avanzadada que el
‘maestro/origen’ por una confirmación
Esto significa que hemos commit 1 cambio en el
repositorio local, pero que este no se está en el repositorio de origen
(origin), no se ha hecho push, donde origen es el nombre
que se usa típicamente para el repositorio en GitHub. Entonces,
confirmemos los cambios pendientes, para esto seleccione la caja
staged y luego escriba el mensaje describiendo el commit
(fig. @ref(fig:rstudioCommit2)).
Captura de pantalla con los archivos a confirmar sus cambios y el texto descriptivo de la confirmación.
Cuando haya terminado no habrán mas cambios pendientes en el panel Git y el repositorio estará completamente limpio.
Fíjese que ahora el mensaje dice:
Your branch is ahead of ‘origin/master’ by 2
commits.
_Su rama esta más avanzadada que el ‘maestro/origen’ por 2
confirmación
Estas 2 confirmaciones son las dos que acabamos de hacer y no se han empujado (push) aun a GitHub. Haciendo clic en el botón History (historial), podemos ver que hay un total de 4 commit en el repositorio local, mientras hay sólo 2 en GitHub (fig. @ref(fig:rstudioCommit3)).
Captura de pantalla con 4 commits.
Ahora que se han hecho todos los cambios deseados en el repositorio local, usted puede empujar (push) los cambios a GitHub usando el botón Push. Se abrirá una ventana donde se pregunta por su usuario y password de GitHub, luego los cambios serán enviados. Esto dejará su repositorio local en un estado totalmente limpio y sincronizado con el repositorio remoto. Terminado esto, en el historial (en GitHub) se muestran todos los commits, incluyendo los 2 que fueron hechos en GitHub y los 2 que se hicieron en forma local con RStudio.
Captura de pantalla con los 4 modificaciones confirmadas.
Ahora puede ver que las etiquetas del repositorio local
(HEAD) y del remoto (origin/HEAD) están
apuntando a la misma versión en el historial. De esta forma, si miramos
el historial de los commits en GitHub serán iguales a los que tenemos en
forma local.
Captura de pantalla con el historial de cambios en github.
Es claro que una buena documentación es crítica para hacer del historial de versiones significativo y útil. Es tentador saltarse la escritura del mensaje asociado al commit o escribir algo por defecto como ‘Actualización!’. Sin embargo es importante escribir mensajes que sean para entender en el futuro que se hizo y por qué. Ademas, los mensajes que se usan en commits son en general más fáciles de entender si usan una convención de verbos activos. Por ejemplo, se puede ver que los mensajes de commit en las capturas de pantallas comienzan siempre con un verbo en pasado (en inglés!) y que explican que fue lo que se cambió.
Si bien muchos de los cambios que aquí se hicieron son simples y se explican por si mismos, para cambios más complejos, es mejor entregar un mensaje completo y auto-contenido. La convención, sin embargo, es tratar de usar mensajes cortos, con una sentencia breve, seguido de una explicación más detallada y racional para el cambio. Esto permite que el nivel de detalles sea legible en el registro de las versiones (version log). No puedo contar el número de veces que he visto los registro d e commits de hace 2, 3 o 10 años y agradecido el nivel de diligencia de los colaboradores que se tomaron el tiempo de describir el trabajo que se realizó.
Hasta ahora nos hemos enfocado al uso de Git y GitHub para el uso personal, como ya se demostró esto es extremadamente útil. Sin embargo donde git y GitHua brilla es cuando se comparte un repositorio GitHub con colaboradores, de esta forma se pede trabajar en un código, análisis y modelos en forma colaborativa. Cuando se trabaja de esta manera con otros investigadores, es muy importante poner atención al estado del repositorio remoto para evitar potenciales conflictos al combinar el trabajo. Un merge conflict ocurre cuando dos colaboradores hacen 2 commits en forma separada donde se ha(n) cambiado(s) la(s) misma(s) línea(s) de código de un archivo. Cuando esto ocurre, git no puede combinar los cambios en forma automática y arroja un error preguntando como resolver el conflicto. Esto no es grave, no es necesario tenerle miedo a los merge conflicts ya que son muy fáciles resolver y aquí hay algunas guías geniales. de como hacerlo (por ahora sólo en inglés).
Dicho esto, es siempre mejor evadir este tipo de conflictos, lo que se pueden minimizar siguiendo las siguientes sugerencias:
Use RStudio para agregar un nuevo archivo al repositorio
sasap-test, desarrolle una estructura básica y
guárdela.
A continuación stage y commit el archivo en forma local y luego push it a GitHub.
Hay mucho que no hemos visto en este tutorial. Existen tutoriales muy completos que cubren tópicos mas avanzados. Algunos de estos temas son:
Usando git en la linea de comándos.
Resolviendo conflictos.
Branching y merging.
Pull requests versus contribuciones directas por colaboradores.
Usando .gitignore para proteger datos sensitivos.
GitHub Issues y por que son útiles.
y más, mucho más.
Try Git es un tutorial interactivo muy bueno y completo.
Software Carpentry Version Control with Git
Codecademy Learn Git (some paid)